{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to atomman: Load and dump conversions\n",
    "\n",
    "__Lucas M. Hale__, [lucas.hale@nist.gov](mailto:lucas.hale@nist.gov?Subject=ipr-demo), _Materials Science and Engineering Division, NIST_.\n",
    "    \n",
    "[Disclaimers](http://www.nist.gov/public_affairs/disclaimer.cfm) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Introduction<a id='section1'></a>\n",
    "\n",
    "Atomman features an number of built-in converters between the atomman.System class and other representations of atomic configurations. This includes text-based representations for storing atomic information as files, and representations used by other Python packages. All conversions between the different format options are handled in a similar manner by defining the two operations\n",
    " \n",
    " - **load** creates a System object based on another representation.\n",
    " \n",
    " - **dump** converts a System object to another representation.\n",
    " \n",
    "**NOTE**: Some of the load/dump styles have additional Python package requirements in order to work. Check the documentation on each style for more details."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Load<a id='section2'></a>\n",
    "\n",
    "Each style defines its own load function, which can be called directly as atomman.load_&lt;style&gt;(), (e.g. atomman.load_poscar()) or by calling atomman.load(style). The underlying code for the load functions can be found in the atomman/load directory.\n",
    "\n",
    "### 2.1. atomman.load_&lt;style&gt;()\n",
    "\n",
    "Style-specific load functions.\n",
    "\n",
    "Parameters\n",
    "\n",
    "- **content** (*any*) the content to be loaded.  For text formats, can be a str of the content, a file path or a file-like object.\n",
    "\n",
    "- **\\*\\*kwargs** (*any*) any extra style-specific keyword arguments.\n",
    "\n",
    "### 2.2. atomman.load()\n",
    "\n",
    "Common load function that can be used for any style. Convenient for loading user-specified data as the format style is a string parameter.\n",
    "\n",
    "Parameters\n",
    "\n",
    "- **style** (*str*) indicates the format of the content being loaded.\n",
    "\n",
    "- **content** (*any*) the content to be loaded.  For text formats, can be a str of the content, a file path or a file-like object.\n",
    "\n",
    "- **\\*\\*kwargs** (*any*) any extra style-specific keyword arguments."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Dump<a id='section3'></a>\n",
    "\n",
    "Similarly, each style defines its own dump function that can be called with atomman.dump_&lt;style&gt;() or atomman.dump(style). The underlying code for the dump functions can be found in the atomman/dump directory.\n",
    "\n",
    "### 3.1. atomman.dump_&lt;style&gt;()\n",
    "\n",
    "Style-specific dump functions.\n",
    "\n",
    "Parameters\n",
    "\n",
    "- **system** (*atomman.System*) The system to convert.\n",
    "\n",
    "- **\\*\\*kwargs** (*any*) any extra style-specific keyword arguments.\n",
    "\n",
    "### 3.2. atomman.dump()\n",
    "\n",
    "Common dump function that can be used for any style.\n",
    "\n",
    "Parameters\n",
    "\n",
    "- **style** (*str*) indicates the format of the content to dump to.\n",
    "\n",
    "- **system** (*atomman.System*) The system to convert.\n",
    "\n",
    "- **\\*\\*kwargs** (*any*) any extra style-specific keyword arguments.\n",
    "\n",
    "### 3.3. System.dump()\n",
    "\n",
    "The System class also defines a dump() method that calls atomman.dump() on itself. \n",
    "\n",
    "Parameters\n",
    "\n",
    "- **style** (*str*) indicates the format of the content to dump to.\n",
    "\n",
    "- **\\*\\*kwargs** (*any*) any extra style-specific keyword arguments."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Supported styles<a id='section4'></a>\n",
    "\n",
    "This is the list of currently supported styles and links to more in-depth discussion of each.\n",
    "\n",
    "[system_model](1.4.1. system_model conversions.ipynb) The JSON/XML data model designed for representing all data associated with an atomman.System object.\n",
    "\n",
    "[poscar](1.4.2. POSCAR conversions.ipynb) POSCAR is a common text format used by VASP and other DFT-centric codes.\n",
    "\n",
    "[cif](1.4.3. CIF conversions.ipynb) CIF is a standard format for representing crystallographic data.\n",
    "\n",
    "[table](1.4.4. table conversions.ipynb) \n",
    "\n",
    "[atom_data](1.4.5. LAMMPS data file conversions.ipynb) LAMMPS data files used to define initial atomic data.\n",
    "\n",
    "[atom_dump](1.4.6. LAMMPS dump file conversions.ipynb) LAMMPS dump files used to retrieve computed atomic properties.\n",
    "\n",
    "[ase_Atoms, phonopy_Atoms](1.4.7. ase and phonopy conversions.ipynb) The Python class representation of atomic systems used by the [ase](https://wiki.fysik.dtu.dk/ase/) and [phonopy](https://atztogo.github.io/phonopy/) Python packages.\n",
    "\n",
    "[pymatgen_Structure](1.4.8. pymatgen conversions.ipynb) The Python class representation of atomic systems used by the [pymatgen](http://pymatgen.org/) Python package.\n",
    "\n",
    "[spglib_cell](1.4.9. spglib conversions.ipynb) The atomic data used by the [spglib](https://atztogo.github.io/spglib/python-spglib.html) Python package for analyzing space group information.\n",
    "\n",
    "[prototype](1.4.10. prototype loading.ipynb) A crystal_prototype record found in the NIST Interatomic Potentials Repository database.\n",
    "\n",
    "[crystal](1.4.11. crystal loading.ipynb) A relaxed_crystal record found in the NIST Interatomic Potentials Repository database.  Each relaxed crystal is specific to an interatomic potential.\n",
    "\n",
    "[dft_reference](1.4.12. DFT reference crystal loading.ipynb) A reference crystal structure from a DFT database (Materials Project or OQMD). "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "  "
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
